p-map

What is p-map?

The p-map npm package is a library that allows you to map over promises concurrently, controlling the number of promises that are running at any given time. It is useful for throttling asynchronous operations that are initiated in a loop, such as API calls, file operations, or any task that returns a promise.

What are p-map's main functionalities?

Concurrency Control

This feature allows you to control the number of promises that are executed concurrently. In the code sample, `pMap` is used to fetch a list of URLs with a concurrency limit of 2, meaning only 2 promises will be running at the same time.

const pMap = require('p-map');

const urls = [/* ... */];
const fetchUrl = async url => {/* ... */};

(async () => {
  const result = await pMap(urls, fetchUrl, {concurrency: 2});
  console.log(result);
})();

Error Handling

p-map provides options for error handling. In this example, `stopOnError` is set to false, which means that p-map will not stop mapping over the remaining items when one promise rejects. Instead, it will continue with the rest and collect all the errors.

const pMap = require('p-map');

const tasks = [/* ... */];
const doTask = async task => {/* ... */};

(async () => {
  try {
    const result = await pMap(tasks, doTask, {concurrency: 4, stopOnError: false});
    console.log(result);
  } catch (error) {
    console.error('An error occurred:', error);
  }
})();

Promise Cancellation

p-map supports promise cancellation when used with cancelable promises, such as those created with the p-cancelable package. This allows you to cancel the execution of the promises if needed.

const pMap = require('p-map');
const {CancelablePromise} = require('p-cancelable');

const tasks = [/* ... */];
const cancellableTask = task => new CancelablePromise(resolve => {/* ... */});

(async () => {
  const mapper = cancellableTask;
  const result = await pMap(tasks, mapper, {concurrency: 3});
  console.log(result);
})();

Other packages similar to p-map

bluebird

Bluebird is a comprehensive promise library that includes a 'map' function with concurrency control. It offers a broader set of features for promise manipulation and is often considered a more heavyweight alternative to p-map.

async

The async library provides a wide range of functions for working with asynchronous code, including 'mapLimit' which is similar to p-map's functionality. Async is callback-based but also supports promises, and it is more general-purpose compared to the more focused p-map.

promise-map-series

promise-map-series is a simpler alternative that maps over a list of values in series, resolving promises one after the other, rather than controlling concurrency like p-map.

promise-pool

promise-pool is another library for handling multiple promises concurrently. It provides a pool abstraction that allows you to add tasks to a queue and process them with a controlled concurrency, similar to p-map but with a different API design.

README

p-map

Map over promises concurrently

Useful when you need to run promise-returning & async functions multiple times with different inputs concurrently.

Install

$ npm install p-map

Usage

const pMap = require('p-map');
const got = require('got');

const sites = [
	getWebsiteFromUsername('https://sindresorhus'), //=> Promise
	'https://ava.li',
	'https://github.com'
];

(async () => {
	const mapper = async site => {
		const {requestUrl} = await got.head(site);
		return requestUrl;
	};

 	const result = await pMap(sites, mapper, {concurrency: 2});

	console.log(result);
	//=> ['https://sindresorhus.com/', 'https://ava.li/', 'https://github.com/']
})();

API

pMap(input, mapper, options?)

Returns a Promise that is fulfilled when all promises in input and ones returned from mapper are fulfilled, or rejects if any of the promises reject. The fulfilled value is an Array of the fulfilled values returned from mapper in input order.

input

Type: Iterable<Promise | unknown>

Iterated over concurrently in the mapper function.

mapper(element, index)

Type: Function

Expected to return a Promise or value.

options

Type: object

concurrency

Type: number (Integer)
Default: Infinity
Minimum: 1

Number of concurrently pending promises returned by mapper.

stopOnError

Type: boolean
Default: true

When set to false, instead of stopping when a promise rejects, it will wait for all the promises to settle and then reject with an aggregated error containing all the errors from the rejected promises.

p-map for enterprise

Available as part of the Tidelift Subscription.

The maintainers of p-map and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Related

• p-all - Run promise-returning & async functions concurrently with optional limited concurrency
• p-filter - Filter promises concurrently
• p-times - Run promise-returning & async functions a specific number of times concurrently
• p-props - Like Promise.all() but for Map and Object
• p-map-series - Map over promises serially
• p-queue - Promise queue with concurrency control
• More…